package com.googlecode.framework.web.pagination;

import java.util.Map;

public interface Href extends Cloneable, java.io.Serializable {

    /**
     * Adds a parameter to the href.
     * @param name String
     * @param value Object
     * @return this Href instance, useful for concatenation.
     */
    Href addParameter(String name, Object value);

    /**
     * Removes a parameter from the href.
     * @param name String
     */
    Object removeParameter(String name);

    /**
     * Getter for the map containing link parameters. The returned map is always a copy and not the original instance.
     * @return parameter Map (copy)
     */
    Map getParameterMap();

    /**
     * Adds all the parameters contained in the map to the Href. The value in the given Map will be escaped before
     * added. Any parameter already present in the href object is removed.
     * @param parametersMap Map containing parameters
     */
    void setParameterMap(Map parametersMap);

    /**
     * Adds all the parameters contained in the map to the Href. The value in the given Map will be escaped before
     * added. Parameters in the original href are kept and not overridden.
     * @param parametersMap Map containing parameters
     */
    void addParameterMap(Map parametersMap);

    /**
     * Getter for the base url (without parameters).
     * @return String
     */
    String getBaseUrl();

    /**
     * Set the full url, overriding any existing parameter.
     * @param url full url
     */
    void setFullUrl(String url);

    /**
     * Returns the URI anchor.
     * @return anchor or <code>null</code> if no anchor has been set.
     */
    String getAnchor();

    /**
     * Setter for the URI anchor.
     * @param name string to be used as anchor name (without #).
     */
    void setAnchor(String name);

    /**
     * toString: output the full url with parameters.
     * @return String
     */
    String toString();

    /**
     * @see java.lang.Object#clone()
     */
    Object clone();

    /**
     * @see java.lang.Object#equals(Object)
     */
    boolean equals(Object object);
}
